Configuring ODBC Client Data Sources on Windows

To configure client data sources for the ODBC Client on Windows platforms, you use the ODBC Administrator.

Configuring ODBC User and System Client Data Sources

Start the ODBC Administrator. To start the ODBC Administrator, select Start / Programs. From the Programs menu, select DataDirect SequeLink 6.0 Client for ODBC or DataDirect SequeLink 6.0 Client for ODBC 64-bit, and then select the ODBC Administrator application.
Click the User DSN tab or the System DSN tab to list user or system data sources, respectively.





To configure a new data source, click the Add button. A list of installed drivers appears. Select DataDirect SequeLink 6.0; then, click Finish.

NOTE: To change an existing data source, select the data source you want to configure and click the Configure button.

The DataDirect SequeLink for ODBC Setup window appears.





On the General tab, provide the following information; then, click Apply.

Data Source Name: Type a unique name that identifies this ODBC data source configuration. Examples are Accounting or SequeLink to Oracle Data.

Description: Optionally, type a description of the data source, for example, My Accounting Database or Accounting Data in Oracle (SSL).

SequeLink Server Host: Type the TCP/IP host name of the SequeLink service to which the ODBC Client will connect.

SequeLink Server Port: Type the TCP/IP port the SequeLink service is listening on for connection requests. The port you specify must be the same port that was specified for the SequeLink service when the SequeLink Server was installed; the default is 19996.

Server Data Source: Type the name of a server data source configured for the SequeLink service to use for the connection, or click the ... button to select an existing server data source. This field is optional. If a server data source is not specified, the default server data source for that SequeLink service is used.

Use LDAP: To configure the ODBC Client to retrieve connection information from an LDAP directory, select the Use LDAP check box. The fields change on the lower half of the screen to accommodate the information required to query an LDAP server for connection information. Provide the following information:

LDAP Server Host: Type the TCP/IP host name of the LDAP server.

LDAP Server Port: Type the TCP/IP port the LDAP server is listening on for connection requests.

Distinguished Name (DN): Type an identifier that uniquely identifies the LDAP entry where the connection information is stored.

Encrypted (SSL): If the remote SequeLink service is configured for Secure Sockets Layer (SSL) encryption, select this check box. If connecting to a SequeLink service enabled for SSL, you must select this check box.

When the check box is cleared (the default), communication between the SequeLink Client and SequeLink Server is not encrypted.

Configuration of encryption is performed on the SequeLink Server. See "Using SSL Encryption" for a discussion of encrypting data.

NOTES:

An ODBC client data source can reference an LDAP directory to retrieve server connection information. See "Retrieving Connection Information from LDAP Directories" for more information about retrieving connection information from LDAP directories.
SSL encryption is not supported for LDAP Servers. The Use LDAP and the Encrypted (SSL) check boxes are mutually exclusive.
SSL encryption is not supported for SequeLink Server for DB2 for z/OS. Do not select the Encrypted (SSL) check box for a DB2 for z/OS configuration.

Translate: Click Translate only if you want to configure an ODBC translator.

NOTE: We strongly recommend that you do not configure an ODBC translator; instead, rely on the native SequeLink transliteration between server and client code pages.

The Select Translator dialog box appears, listing translators specified in the ODBC Translators section of the system information file. Select a translator. When satisfied with your choice, click OK to close this dialog box and perform the translation.

Optionally, click the Failover tab to specify Failover data source settings.





Provide any of the following information; then, click Apply.

Load Balancing: Select this check box to allow the driver to use client load balancing in its attempts to connect to primary and alternate database servers. In this case, the driver attempts to connect to the database servers in random order.

If this check box is not selected (the default), client load balancing is not used and the driver connects to each database server based on its sequential order (primary server first, then, alternate servers in the order they are specified).

NOTE: This option has no effect unless alternate servers are defined for the Alternate Servers connection option.

The Load Balancing option is an optional setting that you can use in conjunction with connection failover. See "Configuring Connection Failover for the ODBC Client" for a discussion of connection failover and for information about other connection options that you can set for this feature.

Alternate Servers: Type a list of alternate SequeLink servers to which the driver will try to connect if the primary SequeLink server is unavailable, using a string that defines the physical location of each alternate server. Specifying a value for this option enables connection failover for the driver. See "Configuring Connection Failover for the ODBC Client" for a discussion of connection failover.

IMPORTANT: If you specified an LDAP server in the LDAP Server Host field, the alternate servers must be LDAP servers.

The server name and port are required for each alternate server entry. All of the other required connection information for each alternate server is the same as what is defined for the primary server connection. Currently, the only optional property that can be set for the alternate server is Server Data Source.

The string has the format:

(Host=servername1:Port=port1[:ServerDataSource=serverdatasourcename1], Host=servername2:Port=port2[:ServerDataSource=serverdatasourcename2],...)

For example, the following Alternate Servers value defines two alternate SequeLink servers for connection failover:

(Host=server2:Port=19996:ServerDataSource=SDSN2,Host=server3:Port=19996:ServerDataSource=SDSN3)

If you are connecting to an LDAP server, the syntax includes the physical location of the server and the port number:

(Host=ld1.foo.com:Port=389,Host=ld2.foo.com:Port=389,Host=ld3.foo.com:Port=389)

Connection Retry Count: Type a value to specify the number of times the driver tries to connect to the primary server and, if configured, to the alternate servers after the initial unsuccessful attempt.

Valid values are integers from 0 to 65535. When set to 0 (the default), the driver does not try to connect after the initial unsuccessful attempt.

If a connection is not established during the retry attempts, the driver returns an error that is generated by the first server to which it tried to connect.

This option and the Connection Retry Delay connection option, which specifies the wait interval between attempts, can be used in conjunction with connection failover.

See "Configuring Connection Failover for the ODBC Client" for a discussion of connection failover and for information about other connection options that you can set for this feature.

Connection Retry Delay: Type a value to specify the number of seconds that the driver waits after the initial unsuccessful connection attempt before retrying a connection to the primary server and, if specified, to the alternate servers.

Valid values are integers from 0 to 65535. The default value is 3 (seconds). When set to 0, there is no delay between retries.

NOTE: This option has no effect unless the Connection Retry Count connection option is set to an integer value greater than 0.

This option and the Connection Retry Count connection option, which specifies the number of times the driver tries to connect after the initial unsuccessful attempt, are used in conjunction with connection failover.

See "Configuring Connection Failover for the ODBC Client" for a discussion of connection failover and for information about other connection options that you can set for this feature.

Force SQL_DRIVER_NOPROMPT: Select this check box when connection failover or load balancing is enabled. This check box must be also selected if the application cannot change the DriverCompletion argument to SQL_DRIVER_NOPROMPT.

If this check box is not selected (the default), the behavior of the application is not changed.

At any point during the configuration process, you can click Test Connect to attempt to connect to the data source using the connection properties specified in the driver Setup dialog box. A logon dialog box appears; see "ODBC Connection Dialogs" for details.

Note that the information you enter in the logon dialog box during a test connect is not saved.

If the driver can connect, it releases the connection and displays a Connection Established message. Click OK.
If the driver cannot connect because of an improper environment or incorrect connection value, it displays an appropriate error message. Click OK.

NOTE: If you are configuring alternate servers for use with the connection failover feature, be aware that the Test Connect button tests only the primary server, not the alternate servers.

Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values.

Configuring ODBC File Client Data Sources

File data sources are data source files stored on a file server. The files are available to any user who can access the server.

To configure ODBC file client data sources:

Start the ODBC Administrator by clicking Start / Programs. From the Programs menu, select DataDirect SequeLink 6.0 Client for ODBC or DataDirect SequeLink 6.0 Client for ODBC 64-bit, and then select the ODBC Administrator application.
Click the File DSN tab. The File DSN tab lists any file data sources in the specified directory.





To configure a new data source, click the Add button. A list of installed drivers appears. Select DataDirect SequeLink 6.0; then, perform one of the following actions:
To configure the file data source to connect directly to a SequeLink Server without retrieving connection information from an LDAP directory, click OK. Then, skip to Step 5.
To configure the file data source to retrieve connection information from an LDAP directory, continue with the next step.
Click Advanced. The Advanced File DSN Creation Settings window appears.





In the Type driver-specific keywords and values scrollable box, type the values required to make the connection, such as the host name and port, as well optional values. For example, type UseLDAP=1 to configure the ODBC Client to retrieve connection data from an LDAP server, or type Encrypted=1 when the remote Agent is configured for SSL encryption. Then, click OK. You are returned to the list of drivers. Click Next and continue with Step 5.

The Create New Data Source dialog box appears.





Type the name of the file data source you want to create or click Browse to select an existing file data source; then, click Next.

The Create New Data Source dialog box displays the settings you've configured for this data source.





Click Finish to create the file data source. A series of connection dialogs appear as described in "ODBC Connection Dialogs". The file data source will be saved after you enter the correct information in the connection dialog boxes.

ODBC Connection Dialogs

A SequeLink data access connection involves the following stages:

A network connection is established.
An authentication mechanism is used to establish the identity of the SequeLink Client to the SequeLink Server.
Based on information provided by the SequeLink Client application (for example, a database user name and password), a database connection is established.

Stage 1: Establishing a Network Connection

The first stage of the connection process involves establishing a network connection. The dialog box that appears depends on whether the connection has been configured to connect directly to a SequeLink service or to retrieve connection information for the SequeLink service from a centralized LDAP directory.

Connecting Directly to a SequeLink^® Service

If the connection has been configured to connect directly to a SequeLink service, the Connect to the SequeLink Server dialog box appears.

Provide the following information; then, click OK.

SequeLink Server Host: Type the TCP/IP host name of the SequeLink service.

SequeLink Server Port: Type the TCP/IP port on which the SequeLink service is listening. A default installation of SequeLink Server uses the port 19996.

Server Data Source: Type the name of a server data source to use for the connection, or select one from the drop-down list. This step is optional. If a server data source is not specified, the default server data source for that service will be used for the connection.

Retrieving Connection Information from an LDAP Directory

If the connection has been configured to connect to an LDAP server to retrieve connection information from an LDAP directory, the Connect to the SequeLink Server dialog box appears.

See "Creating LDAP Entries for SequeLink® Services" for information on setting up an LDAP server for SequeLink.

Provide the following information; then, click OK.

LDAP Server Host: Type the TCP/IP host name of the LDAP server.

LDAP Server Port: Type the TCP/IP port on which the LDAP server is listening.

Distinguished Name: Type the Distinguished Name (DN) of the LDAP entry.

Stage 2: SequeLink^® Server Authentication

The second stage of the connection process involves authentication of the SequeLink Client to the SequeLink Server. The dialog boxes that appear depend on how authentication is configured for the SequeLink service.

When ServiceAuthMethods=anonymous or ServiceAuthMethods=integrated_nt, no dialog boxes appear.
When ServiceAuthMethods=OSLogon(HUID,HPWD) or ServiceAuthMethods=OSLogon(UID,PWD), the Logon to SequeLink Service dialog box appears.





Provide the following information; then, click OK.

Host User Name: Type the host user name.

NOTE: When connecting to a Windows server, you must prefix the host user name with a server name, if authenticating to a local server, or a domain name (for example, SALES\DJONES). If the server name or domain name is omitted, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the machine on which the SequeLink Server is running. If this validation fails, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the domain of the machine on which the SequeLink Server is running.

Host Password: Type the host password.

When ServiceAuthMethods=OSLogon(HUID,HPWD,NPWD) or ServiceAuthMethods=OSLogon(UID,PWD,NPWD) and the password is expired, the Password expired. Please specify new password dialog box appears.





NOTE: If the password is not expired, the Logon to SequeLink Service dialog box appears, prompting only for the host user name and host password.

Provide the following information; then, click OK.

Host User Name: Type the host user name.

NOTE: When connecting to a Windows server, you must prefix the host user name with a server name, if authenticating to a local server, or a domain name (for example, SALES\DJONES). If the server name or domain name is omitted, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the machine on which the SequeLink Server is running. If this validation fails, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the domain of the machine on which the SequeLink Server is running.

Host Password: Type the host password.

New Password: Type the new password to be used by the SequeLink password change mechanism.

Confirm Password: Type the new password again to confirm it.

For more information about configuring authentication, see "Configuring SequeLink® Security".

Stage 3: Data Store Logon

The last stage of the connection process involves logging on the data store. The dialog boxes that appear depend on the data store logon method configured for the SequeLink service:

When DataSourceLogonMethod=OSIntegrated, no dialog boxes appear.
When DataSourceLogonMethod=DBMSLogon(UID,PWD) or DataSourceLogonMethod=DBMSLogon(DBUID,DBPWD), a data store-specific user name and password are required and the Logon to SequeLink Service dialog box appears.





Provide the following information; then, click OK.

Database User Name: Type the database logon ID.

Database Password: Type the database password.

Database: Type the name of the database to which you want to connect. This field is disabled when the data store does not recognize the concept of databases.

For more information about configuring authentication, see "Configuring SequeLink® Security" about configuring data store logon methods.

Testing ODBC Connections on Windows

On the SequeLink Client, start the ODBC Administrator. To start the ODBC Administrator, select Start / Programs. From the Programs menu, select DataDirect SequeLink 6.0 Client for ODBC or DataDirect SequeLink 6.0 Client for ODBC 64-bit, and then select the ODBC Administrator application. The ODBC Data Source Administrator window appears listing resident data sources.





Create an ODBC data source as described in "Configuring ODBC User and System Client Data Sources" specifying the TCP/IP address and TCP/IP port of the SequeLink service.
Click the Test Connect button to test the connection. If successful, a dialog appears telling you the connection was successful. You are now ready to start using your ODBC applications with SequeLink.